<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:freshdox="http://www.keithpower.com/freshdox/freshdox">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<link rel="stylesheet" type="text/css" href="freshdox-default-style.css" />

<title>Untitled Document</title>
</head>

<body>

<freshdox:test name="second">
  <freshdox:code>
    String str = new String();
    str+="moo"; 
  </freshdox:code><br/>
  <freshdox:condition>
    str!=null &amp;&amp; str.length()>0
  </freshdox:condition><br/>
</freshdox:test>
Other stuff<br />
<br />
<h2>Overview </h2>
<p>test is analogous to the the <a href="python">doctest</a> tool available for <a href="python">Python</a>. It allows the user to embed Java snippets into documentation. This has several benefits, but chiefly that you can ensure that your documentation is always up to date. Each time you change your code, you can just run test against your documentation, and see any errors. test is coded so that it can be embedded into a JUnit test if required. </p>
<p>Here's what the code for an embedded test looks like:</p>
<table border="1" cellspacing="0" cellpadding="2">
  <tr>
    <td bgcolor="#996666"><pre class="style2">&lt;freshdox:test name=&quot;second&quot;&gt;<br/>  &lt;freshdox:code&gt;<br/>    String str = new String();<br/>    str+=&quot;moo&quot;; <br/>  &lt;/freshdox:code&gt;&lt;br/&gt;<br/>  &lt;freshdox:condition&gt;<br/>    str!=null &amp;&amp; str.length()&gt;0<br/>  &lt;/freshdox:condition&gt;&lt;br/&gt;<br/>&lt;/freshdox:test&gt;<br/>
    </pre>
    </td>
  </tr>
</table>
<p>Here's what one looks like in practice, using the default stylesheet:</p>
<freshdox:test name="second">
<freshdox:config name="path" value="x, y, z"/>
<freshdox:code>String str = new String();
    str+="moo"; 
  </freshdox:code><freshdox:condition>
    str!=null &amp;&amp; str.length()>0
  </freshdox:condition></freshdox:test>
<p>Note that the condition is hidden using the default style sheet. You can develop your own stylesheets to format the code and condition as you wish.</p>
<p>Here's another test, that tests test</p>
<test name="test" class="test"> <teststdin>No keyboard input<br/>
</teststdin> <code> org.test.test tester = new org.test.test("doc2.htm"); String output = tester.doTests(); </code><br/>
            <condition> output.length()==0 </condition><br/>
</test>
<p>( doc2.htm is a copy of this file, but without this test. Referring to this same doc in the test would produce an infinite loop. ) </p>
<p>To try this out just run like this: <span class="style1">java -cp tester.jar org.tester.tester doc.htm</span> </p>
<p><strong>Input, output, redirection.</strong></p>
<p>You can provide input in the stdin tag. Output can be accessed in the condition, via the testRun.output/err variables, like so: </p>
<p><strong>Depends on previous runs</strong></p>
<p>You can chain tests, so that they depend on one another. So, in one test you could create a String variable, and in a later test refer to that String. However, if one test fails, no further tests will be carried out, unless the depends attribute in the test tag is set to false. </p>
<p><strong>referring to details of lastRun </strong></p>
<p>In a test, you can refer to the the output and err from the last tests, via the testRun.lastOutput/Err variables</p>
<p>That's more or less all there is to it. </p>
<p><strong>Credits</strong></p>
<p>Currently, this system uses BeanShell to execute the Java code. The idea is taken from doctest.</p>
<p><strong>Future Work</strong></p>
<p>I'd like to see this integrated with Eclipse, so that as you type your documentation, including tests, Eclipse will highlight errors, and present you with the Quick Fix menu. This will allow the construction of the bones of your application just by writing your documentation, making for a very nice development environment.</p>
<p>Currently, you can do this by making a new class in your project and pasting in all the test code, and using the QuickFix feature. Or alternatively, just run:</p>
<p> <span class="style1">java -cp tester.jar org.tester.tester -printjava doc.htm</span></p>
<p>and paste that into your class. </p>

<p><br />
  Misc tests
</p>
<p>Spread over 2 tests:</p>
<p>Declare vars, note no check:</p>
<freshdox:test name="split1" >
  <freshdox:code>
		int a=666, b=999;	 	 
  </freshdox:code><br/>
</freshdox:test>

<p>Access vars from last test, or redeclare. </p>
<freshdox:test name="split2" >
  <freshdox:code>
		int b = 666;	 	 
  </freshdox:code><br/>
  <freshdox:condition>
    a==b;
  </freshdox:condition><br/>
</freshdox:test>

<p>Make a class </p>
<freshdox:test name="nonstrict" >
  <freshdox:code>
		String s = "willy";
  </freshdox:code><br/>
  <freshdox:condition>
		s.equals("willy")
  </freshdox:condition><br/>
</freshdox:test>

<p>Make a class </p>
<freshdox:test name="makeclass" >
  <freshdox:code>
		class TestClass
		{
			<b>public int x=7;</b>
		};

  </freshdox:code><br/>
    <freshdox:condition>
		TestClass tc = new TestClass();
		tc.x==17;
  </freshdox:condition><br/>
</freshdox:test>

</body>
</html>
